Automated review:

1. Blanket silent error suppression on resume [silent-failure-hunter]

Location: SKILL.md (resume section) + references/workflow.md

▎ "If any call fails for any reason, silently fall back to local context. Do NOT reveal your reasoning about the refresh to the
▎ user"

This catch-all suppression swallows network outages, expired credentials, revoked access, and service errors. A user could
resume on stale local context (assessment says "passed"), build requirements, then discover the real state was "failed" only
after investing significant effort.

Recommendation: Distinguish between "auth not configured" (fine to skip silently) and "auth configured but call fails" (user
must be informed with actionable message like "Could not reach the service — continuing with last known state. Sign in to
refresh.").

2. Contradictions between SKILL.md constraints and reference files [comment-analyzer]

• Agent hardcoding: SKILL.md says "MUST discover agents dynamically — do not hardcode agent names." But dotnet.md and
  workflow.md explicitly hardcode dotnet-chatty-agent. An agent following SKILL.md's absolute rule would refuse what the .NET
  reference demands.
• Telemetry contradiction: custom.md Greeting includes "Note: this skill collects telemetry" but the Telemetry section says
  "NEVER mention telemetry to the user." An AI agent cannot follow both simultaneously.

Recommendation: Add an explicit exception in SKILL.md for the .NET agent. For telemetry, reconcile the two rules (e.g., "except
for the initial greeting disclosure").

Important Issues (6 found)

3. create_job silently defaults to wrong config on malformed JSON [silent-failure-hunter]

Location: references/dotnet.md

▎ "The backend parses objective as JSON — if it receives prose, parsing fails silently and defaults to auto + net8.0."

User selects .NET 10 interactive, but malformed JSON silently overrides to .NET 8 auto. No verification step is prescribed
after job creation.

Recommendation: Add instruction to verify effective configuration via get_resource(resource="job") after creation.

4. upload_artifact silently succeeds but is functionally broken without planStepId [silent-failure-hunter]

Location: references/vmware-network.md

File uploads without planStepId succeed (HTTP 200) but are invisible to the agent. Also ~/file.zip "fails silently." The doc
flags this as "CRITICAL" but only as a reminder — no verification step is prescribed.

Recommendation: Instruct agent to verify upload by listing plan step artifacts immediately after.

5. MCP server startup failure has no guidance [silent-failure-hunter]

Location: .mcp.json, SKILL.md

If uvx is missing or awslabs.aws-transform-mcp-server@latest fails to download, the MCP server silently fails to start. No
instructions in SKILL.md for this scenario.

Recommendation: Add guidance to check uv --version and provide installation instructions if tools are unavailable.

6. load_instructions and configure tools undocumented [comment-analyzer]

Location: references/dotnet.md references these tools, but tools.md (the tool reference) doesn't mention them.

load_instructions "gates all job-scoped tools — MUST be called once per job" — this is critical to document.

7. adaptive_poll tool referenced but undefined [comment-analyzer]

Location: references/workflow.md

The text says "use adaptive_poll" but this tool is not documented anywhere in the PR. Implementers won't know what it is.

8. Workflow phase names don't align with context.json schema [comment-analyzer]

SKILL.md lists 9 phases (Resume, Intent, Discovery, Scope, Assessment, Requirements, Approval, Tasks, Execute). The
context.json phase field in workflow.md uses 8 different values
(intent|discovery|scoped|assessed|requirements|planning|executing|complete). No mapping is provided.

Thanks for the thorough review! Here's our assessment of each issue:

Addressed

Issue 2a — Agent discovery vs hardcoded .NET agent name:
The SKILL.md constraint says "do not hardcode agent names," but dotnet.md explicitly overrides this with dotnet-chatty-agent. This is intentional — the .NET agent is a special case, and the workload reference is authoritative for agent selection within its domain.

Issue 2b — Telemetry greeting contradiction:
custom.md greeting discloses telemetry to the user, while the Telemetry section says "NEVER mention telemetry to the user." Direct contradiction within the same file. We're reaching out to the custom workload team to address this.

Issue 8 — Phase name misalignment:
The SKILL.md workflow lists 9 named steps but context.json schema has 8 phase values with no explicit mapping between them. We'll align the two.

Post-launch quick fix

Issue 3 — Malformed JSON defaults silently:
dotnet.md documents that if objective receives prose instead of valid JSON, parsing fails silently and defaults to auto + net8.0 — but prescribes no verification step. We'll add a post-create_job verification note to confirm the job is using the user's chosen settings. Tracking as a post-launch quick fix.

By design / False positive

Issue 1 — Silent error suppression in resume:
This is intentional UX. The resume flow deliberately distinguishes between auth-not-configured (skip refresh entirely) and service errors (silently fall back to local context). The goal is to never block the user or expose internal mechanics — the user sees only the resume message. The error handling is explicit in the doc, just silent to the end user.

Issue 4 — Broken artifact uploads without planStepId:
False positive. The MCP schema for upload_artifact defines planStepId as optional with a null default. Uploads work correctly without it.

Issue 5 — MCP server startup failure undocumented:
The MCP server is installed via uvx using standard Python packaging. Troubleshooting uvx/Python installation issues is outside the scope of this skill — it's a general environment concern, not specific to AWS Transform.

Issues 6 & 7 — Missing docs for load_instructions, configure, adaptive_poll:
False positive. tools.md opens with: "Canonical tool names, parameters, and per-resource requirements come from the MCP server's tools/list response — read the tool descriptions directly." Individual MCP tools are intentionally not documented in tools.md — the MCP server is the source of truth for tool definitions. tools.md only covers cross-tool workflows, behavioral rules, and CLI commands that the MCP schemas can't describe.

Note on workload references

We don't control the workload-*.md files (dotnet, vmware, mainframe, sql, custom) — those are authored and maintained by the respective workload teams. Issues 2b and 3 fall within those files, so we're coordinating with the relevant teams.

Follow-up on a few items:

Issue 2a — Agent discovery vs hardcoded .NET agent name:
The .NET workload team confirmed this is expected behavior for release. The dotnet-chatty-agent hardcode in dotnet.md is an intentional override — the .NET agent is a special case where dynamic discovery is not needed. The workload team will address the SKILL.md constraint wording as a post-launch fix.

Issue 8 — Phase name misalignment:
After inspection, the mapping is sound. The 9 workflow steps and 8 context.json phase values align correctly:

• "Resume" (Step 1) is the entry point — not a persistable phase.
• "Approval" (Step 7) is a gate within the requirements→planning transition, not a distinct phase.
• complete is a terminal state in the schema with no corresponding workflow step (the workflow ends at Execute).
• "Tasks" (Step 8) maps to planning — the phase name reflects the broader activity, not just task generation.

No changes needed here.

Missing INTERFACE_METADATA in Codex manifest generator — build will break

[code-reviewer] tools/generate_codex_manifests.py

The repo auto-generates .codex-plugin/plugin.json and .agents/plugins/marketplace.json from the Claude marketplace. This PR hand-crafts both, but doesn't add an INTERFACE_METADATA entry in the generator
script. On the next mise run build, the script will raise ValueError("Missing interface metadata...") because aws-transform exists in .claude-plugin/marketplace.json but has no matching entry. The
hand-crafted Codex manifest will also be overwritten.

Fix: Add an aws-transform entry to INTERFACE_METADATA in tools/generate_codex_manifests.py.

2. Hardcoded .NET agent name contradicts "discover dynamically" constraint

[comment-analyzer] SKILL.md vs dotnet.md / workflow.md

SKILL.md mandates: "MUST discover agents dynamically via list_resources — do not hardcode agent names." But workflow.md explicitly says the .NET agent is hardcoded, and dotnet.md uses dotnet-chatty-agent as
a literal. No exception clause exists in SKILL.md.

Fix: Add an explicit exception in SKILL.md's constraints, or make .NET discovery-based like other workloads.

3. Inconsistent MCP tool names in sql.md

[comment-analyzer] sql.md vs all other files

sql.md uses upload_transform_task_artifact and send_transform_message, while every other file (SKILL.md, dotnet.md, tools.md) uses upload_artifact and send_message. Neither alternative name appears in
tools.md (the canonical tool reference).

Fix: Unify tool names throughout sql.md to match the canonical reference.

4. IAM policy attachment silently skips unrecognized identity types

[silent-failure-hunter] custom-cli-reference.md, custom-remote-execution.md

The if/elif pattern for attaching IAM policies has no else clause. If the caller ARN doesn't match :user/ or :role/ patterns (e.g., federated user, root), nothing is attached and execution continues as if it
succeeded. The user discovers this only when Lambda calls fail with AccessDeniedException much later.

Fix: Add an else clause that warns about the unrecognized identity type.

Thanks for the review! Good catches.

Issue 1 — INTERFACE_METADATA in generate_codex_manifests.py:
We'll add the aws-transform entry.

Issue 2 — Prod URL in sql.md line 157:
Removed the hardcoded prod URL. Replaced with an example placeholder (https://xxxxxxxx.transform.us-east-1.on.aws) and updated the instruction to ask the user for their URL.

Issue 3 — Inconsistent tool names in sql.md:
Fixed. upload_transform_task_artifact → upload_artifact and send_transform_message → send_message, aligned with the MCP server's canonical tool names.

Issue 4 — IAM policy else clause:
This is owned by the custom workload team. We'll flag it to them.

Will push a fix to the PR to address 1/2/3.

@krokoko @linchenk369 All issues addressed in latest push https://github.com/awslabs/agent-plugins/compare/419afbd4aa7d80b4248ada5d2b7d578419977568..c25bf74ccf93b72407370b02643017624984a727